<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Differences From the Tcl Embedding Interface
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot034.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot026.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc64">6.9</A>&nbsp;&nbsp;Differences From the Tcl Embedding Interface</H2>
<A NAME="remotediff"></A>
The remote Tcl interface is designed to be largely compatible with the
embedded Tcl interface, so that a user GUI can be written that allows
either interfaces to be used, while sharing most of the code in both
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and Tcl. An example of this is the Tkeclipse development tools.<BR>
<BR>
Some remote specific code would need to be written. This includes code to
handle the connection and disconnection of the Tcl and ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
sides: there is no equivalent to ec_cleanup in the embedded Tcl interface,
as the termination of the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side should be handled in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. In
addition, the user may need to provide code to restrict the interaction
within the Tcl/Tk GUI when control is transferred to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. Aside from
this, the rest of the code should be reusable, if the user exercises some
care.<BR>
<BR>
The supported compatible methods of communicating between Tcl and
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> in the two interfaces is via the <B>ec_rpc</B> calls and the use
of the I/O queues. The <B>ec_rpc</B> mechanism should behave the same in
both interfaces. For the queues, there are some differences because the
queues are in-memory queues in the embedded interface, but are socket
channels in the remote interface. This leads to the following differences:
<UL CLASS="itemize"><LI CLASS="li-itemize">Data will not appear on the other side until the queue is
 flushed on the side that is generating the output. To make code
 compatible, output queues should be always flushed.<BR>
<BR>
<LI CLASS="li-itemize">In general, reading data via a blocking socket requires the
 size of the data to be explicitly specified, except when I/O is done
 via the EXDR primitives, where size is implicitly specified. Only
 EXDR format is supported when data is sent from Tcl to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>.
 That is, a write handler for a Tcl write channel must write the data
 in EXDR format. For output from the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, the Tcl read
 handler would be supplied with the length of the output when it is
 invoked, and this information must be used if the Tcl read is not
 done via an EXDR primitive. However, in general it is strongly
 suggested that only EXDR formatted data should be sent via the queues
 in both direction.<BR>
<BR>
<LI CLASS="li-itemize">An I/O operation on the stream may block if there is no 
 handler to consume/produce the data on the other side. If a handler
 is specified via the <I>command</I> argument, then a corresponding
 handler in the Tcl side will be invoked at the correct place when the
 ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side produces output or request input.<BR>
<BR>
<LI CLASS="li-itemize">The channel identifier is not of the form <TT>ec_queueX</TT>. To make code portable, the name of the channel should be
 obtained from the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> stream symbolic name or number via the
 commands <B>ec_streamname_to_channel</B> or <B>ec_streamnum_to_channel</B>.<BR>
<BR>
<LI CLASS="li-itemize">Asynchronous queues are bi-directional. In the embedding interface,
 there are no asynchronous queues, and <B>ec_async_queue_create</B> is
 aliased to <B>ec_queue_create</B>, and a uni-directional queue is
 created. Thus for compatibility, these queues should only be used
 in one direction. 
</UL>
In summary, to write code that will work for both the remote and embedded
interfaces, the data should be sent using EXDR format, flush always
performed, and a handler (<I>command</I> argument) provided. The Tcl
channel identifier should not be constructed explicitly.<BR>
<BR>
However, there may be cases where the two interfaces need to be
distinguished. For example, if the Tcl side is to perform some operations
on the file system for the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side (e.g. selecting a file via a
GUI), then with the remote interface, the two sides might not have access
to the same file systems, and being able to distinguish whether the
interface is remote or embedded allows the user to provide code to handle
this. <BR>
<BR>
To obtain information on which interface is being used, use the command:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A NAME="@default154"></A><B>ec_interface_type</B><DD CLASS="dd-description"><BR>
	returns remote for the remote interface, and embedded for the
 embedding interface.
</DL>
<HR>
<A HREF="embroot034.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot026.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
</BODY>
</HTML>
